Chapter {seq chapter} {seq chapter readword} Word Processor File Format{tc "{seq chapter readword} Word Processor File Format"} This document describes the structure of a Psion word processor document file. The description to a level that allows other software to read and write non-password-protected document files. Psion word processor document files contain a file header, followed by a number of type-length-value records, from the following list: • options data • printer-related data • printer model data • page header • page footer • style data • emphasis data • document text • document index Document files created by the word processor will contain records in the order listed above. Each record consists of: • a two-byte record type • a two-byte record length, len • len bytes of data Unless stated otherwise, all dimensions are stored in twips (1/1440 inch). Reserved locations All locations reserved for future use contain a value of zero. The document header{tc "The document header" \l 2} The document header is 40 bytes long. It starts with the 16-byte zero terminated file signature "PSIONWPDATAFILE" followed by a two byte file version number. Following this is a 20-byte struct, containing password data. For a non-password-protected document there are two bytes of zero followed by eighteen bytes, each containing 0xEA. The remaining two bytes of the header are reserved for future use. Record types{tc "Record types" \l 2} The options data record (type 1, length 10){tc "The options data record (type 1, length 10)" \l 3} The options data record contains the following items: UWORD cpos the saved cursor position UBYTE symbols specifies the visibility of screen symbols, as indicated below UBYTE backup/statzoom on the MC, a non-zero value indicates that backup files are to be maintained on the Series 3a this byte stores the current status window and zoom states: the top four bits indicate the current zoom state (0x22 by default) and the lowest four bits indicate the status window size: 0, 1 or 2 for off, small or big respectively this byte is not used on the Series 3 UBYTE style TRUE to show style bar at the left of the text for the OPL program editor, a TRUE value sets the use of a bold typeface UBYTE mono TRUE to load text by line, else by paragraph for the OPL program editor, a TRUE value sets the use of a monospaced typeface UBYTE outlevel lowest outline level to display not used for the OPL program editor UBYTE spare1 reserved for future use, but may contain the OPL program editor data as follows: used by the OPL program editor, where a TRUE value specifies the use of auto indentation. Set to TRUE by default UWORD spare2 reserved for future use, but may contain the OPL program editor data as follows: used by the OPL program editor, to specify the column spacing for tabs. Set to 2 by default Displayed screen symbols are determined by any combination of the following bit fields in symbols: 0x01 0x02 0x04 0x08 0x10 show tabs show spaces show paragraph end markers show hyphens show forced line breaks Printer-related data record (type 2, length 58){tc "Printer-related data record (type 2, length 58)" \l 3} This record contains information required to format the document for the printer and to control the printing process. It includes, amongst other items, descriptions of the page size and margins, the page numbering style, header and footer position and alignment. This record consists of a structure that is used to control the display and WDR printing of formatted text in all applications that require such services. It therefore contains some fields that are not relevant to the word processor. The following description is in terms of the P_EXTENT, SCRLAY_FONT and PAGES_HEADER structs, defined as: typedef struct { WORD x; WORD y; } P_POINT; typedef struct { P_POINT tl; WORD width; WORD height; } P_EXTENT; typedef struct { UWORD fid; /* typeface number */ (1) UWORD style; /* font style */ (2) UWORD height; /* height of font in twips */ } SCRLAY_FONT; typedef struct { SCRLAY_FONT f; /* font data */ UBYTE align; /* header alignment */ (3) UBYTE first_page; /* TRUE to emit on first page */ } PAGES_HEADER; In these terms, the content of the printer-related record is: PAGE DATA WORD width WORD height P_EXTENT body WORD hdtop WORD hdbot WORD pdrflags WORD docflags UWORD pgbeg UWORD pgend page width page height body print region, with respect to top left of page (4) page header position (5) page footer position (6) 0 for portrait, 1 for landscape can be 3 or 0, depending on whether the document has or has not been printed page number to start printing (first page is 1) last page number to print (7) RUNNING PAGE HEADERS PAGES_HEADER top PAGES_HEADER bot page header page footer PAGE NUMBERING WORD offset WORD last WORD style page numbering offset page count, for %m (always reset by pagination) page number style (8) MISCELLANEOUS SCRLAY_FONT f UBYTE size_choice UBYTE wo_control UWORD spare1 UWORD spare2 base font for body print region (9) paper size index (10) TRUE to disable widow and orphan control reserved for future use reserved for future use Notes (1) Typeface numbers are defined in the following list: 0 COURIER 1 PICA 2 ELITE 3 PRESTIGE 4 LETTER_GOTHIC 5 GOTHIC 6 CUBIC 7 LINEPRINTER 8 HELVETICA 9 AVANT_GARDE 10 SPARTAN 11 METRO 12 PRESENTATION 13 APL 14 OCR_A 15 OCR_B 16 STANDARD_ROMAN 17 EMPEROR 18 MADELEINE 19 ZAPF_HUMANIST 20 CLASSIC 21 OPTIONAL_SA 22 OPTIONAL_SB 23 OPTIONAL_SC 24 TIMES_ROMAN 25 CENTURY 26 PALATINO 27 SOUVENIR 28 GARAMOND 29 CALEDONIA 30 BODONI 31 UNIVERSITY 32 SCRIPT 33 SCRIPT_PS 34 OPTIONAL_SCA 35 OPTIONAL_SCB 36 COMMERCIAL_SCRIPT 37 PARK_AVENUE 38 CORONET 39 OPTIONAL_SCC 40 GREEK 41 KANA 42 HEBREW 43 OPTIONAL_A 44 RUSSIAN 45 OPTIONAL_B 46 OPTIONAL_C 47 OPTIONAL_D 48 NARRATOR 49 EMPHASIS 50 ZAPF_CHANCERY 51 OPTIONAL_DA 52 OLD_ENGLISH 53 OPTIONAL_DB 54 OPTIONAL_DC 55 COOPER_BLACK 56 SYMBOL 57 LINE_DRAW 58 MATH_7 59 MATH_8 60 DINGBATS 61 EAN 62 PC_LINE 63 OPTIONAL_SYA A typeface that is not supported by the current printer will be mapped to a supported typeface. See the later Printer driver font mapping section. In addition, a typeface number of -1, indicating an inherited font, is allowed in all emphases and in all paragraph styles except Body text. An emphasis inherits its font from the surrounding paragraph; a paragraph style inherits its font from the Body text style. (2) The font style may be zero, or any sensible combination of the following attributes: 0x01 0x02 0x04 0x08 0x10 underline bold italic superscript subscript Styles or style combinations that are not supported by the current printer are ignored. The value 0x4000 is used internally by the word processor and may or may not be set in the font style data in the document. If set, it can safely be ignored. (3) The running page header alignment may be any one of: 0 1 2 4 5 left aligned right aligned centred 2-column 3-column (4) In terms of the body struct and the page width and height, the page margins are: left top right bottom body.tl.x body.tl.y width-body.tl.x-body.width height-body.tl.y-body.height (5) The page header position measures the vertical distance between the bottom of the header text and the top edge of the page body print region. (6) The page footer position measures the vertical distance between the bottom of the footer text and the bottom edge of the page body print region. (7) To print all pages, the last page number should be set to 0xffff. (8) The page number style is one of: 0 1 2 Arabic Roman, upper case Roman, lower case. (9) The body area base font data is not used by word processor documents. It should always specify the default font, with font number 0 (Courier) a style of 0 (normal) and a size of 240 (12 points). (10) The page size choice should correspond with the earlier page width and height. The following (English) page sizes are recognised: Choice Page type Width Height 0 A4 11906 16838 1 Custom - - 2 Executive 10440 15120 3 Legal 12240 20160 4 Letter 12240 15840 5 Monarch 5580 10800 6 DL 6236 12472 Note that items 2 to 6 may be different in non-English versions of the software. Printer model data record (type 3, variable length){tc "Printer model data record (type 3, variable length)" \l 3} The record consists of a zero terminated string, containing the full path name of the current printer driver file, preceded by a one byte index to the printer model within the file. The default value is: 0 "ROM::\BJ.WDR" Page header record (type 4, variable length){tc "Page header record (type 4, variable length)" \l 3} The record contains the page header text as a zero terminated string. The string may not exceed 80 bytes. Page footer record (type 5, variable length){tc "Page footer record (type 5, variable length)" \l 3} The record contains the page footer text as a zero terminated string. The string may not exceed 80 bytes. Style data record (type 6, length 80){tc "Style data record (type 6, length 80)" \l 3} The file may contain up to 64 such records, each of which defines a single style. The following description is in terms of the SCRLAY_FONT struct (described above) and the SCRLAY_MARGINS, SCRLAY_SPACING and SCRLAY_TABSTOP structs, defined as: typedef struct { UWORD left; /* left margin */ (1) UWORD right; /* right margin */ UWORD indent; /* left margin for first line of a paragraph */ UWORD align; /* alignment */ (2) } SCRLAY_MARGINS; typedef struct { UWORD line; /* space between lines in a paragraph */ UWORD above; /* space above paragraph */ UWORD below; /* space below paragraph */ UWORD flags; /* keep together/next and new page */ (3) } SCRLAY_SPACING; typedef struct { UWORD x; /* tab position */ UWORD type; /* tab type */ (4) } SCRLAY_TABSTOP; In these terms, the content of the style data record is: TEXT sc[2] TEXT tag[16] UWORD sflags SCRLAY_FONT f UWORD inherit SCRLAY_MARGINS marg SCRLAY_SPACING spc UWORD olevel UWORD ntabs SCRLAY_TABSTOP tab[8] two-letter short code (5) style tag name (6) style control flags (7) paragraph base font (8) inherited attributes (9) margin positions paragraph vertical spacing outliner level number of tabstops in following table up to 8 tabstops, in ascending position order Notes (1) Paragraph margins are relative to the page margins (the left and right edges of the body print region). (2) The paragraph alignment may be one of: 0 1 2 3 left aligned right aligned centred justified (3) The spacing flags may be any combination of: 0x01 0x02 0x04 keep on same page as following paragraph keep whole paragraph on one page paragraph starts a new page (4) The tab type may be any one of the following: 0 1 2 left tab right tab centred tab (5) The short code must contain two alphabetic characters and must be unique (it must not be duplicated in either a style or an emphasis). If no meaningful short code can be assigned, it is recommended that unique short codes be generated in the sequence ZA,ZB,...,ZZ,YA,...,YZ,XA,... (6) Although not currently enforced by the software, the text of the tag name should be unique (it should not be duplicated in either a style or an emphasis). If no meaningful tag name can be assigned, it is recomended that the tag name should duplicate the short code. (7) The style control flags may contain any combination of: 0x02 0x04 undeletable default There must be one default style and at least one undeletable style in every document (in all Psion documents they are the same - style BT). It does not make sense for the default style to be deletable. The value 0x8000 is used internally by the word processor and may or may not be set in the style control flags data in the document. If set, it can safely be ignored. (8) In addition to the typeface numbers listed earlier, a typeface number of -1 is used to signify that the typeface and font size are to be inherited from the default style. In such a case the font size is conventionally set to zero. (9) The inherited attributes field may contain any combination of: 0x01 0x02 0x04 underline bold italic For each bit that is set, the corresponding bit in the style field of the SCRLAY_FONT struct must be clear. Inherited attributes are taken from the default style. Emphasis data record (type 7, length 28){tc "Emphasis data record (type 7, length 28)" \l 3} The file may contain up to 16 such records, each of which defines a single emphasis. The following description is in terms of the SCRLAY_FONT struct (described above). In these terms, the content of the emphasis data record is: TEXT sc[2] TEXT tag[16] UWORD sflags SCRLAY_FONT f UWORD inherit two-letter short code (1) emphasis tag name (2) emphasis control flags (3) emphasis font (4) inherited attributes (5) Notes (1) The short code must contain two alphabetic characters and must be unique (it must not be duplicated in either a style or an emphasis). If no meaningful short code can be assigned, it is recommended that unique short codes be generated in the sequence ZA,ZB,...,ZZ,YA,...,YZ,XA,... (2) Although not currently enforced by the software, the text of the tag name should be unique (it should not be duplicated in either a style or an emphasis). If no meaningful tag name can be assigned, it is recomended that the tag name should duplicate the short code. (3) The emphasis control flags must contain the value 0x01, together with any combination of: 0x02 0x04 undeletable default There must be one default emphasis and at least one undeletable emphasis in every document (in all Psion documents they are the same - emphasis NN). It does not make sense for the default emphasis to be deletable. (4) In addition to the typeface numbers listed earlier, a typeface number of -1 is used to signify that the typeface and font size are to be inherited from the enclosing paragraph style (which may itself inherit from the default style). In such a case the font size is conventionally set to zero. (5) The inherited attributes field may contain any sensible combination of: 0x01 0x02 0x04 0x08 0x10 underline bold italic superscript subscript For each bit that is set, the corresponding bit in the style field of the SCRLAY_FONT struct must be clear. Inherited attributes are taken from the enclosing paragraph style (which may itself inherit from the default style). Document text record (type 8, variable length){tc "Document text record (type 8, variable length)" \l 3} This record contains the entire text of the document. Each paragraph, except for the final one, is terminated by a zero. The content conforms with the IBM Code Page 850 symbol set, together with the following additional symbols: Symbol ASCII END_PARAGRAPH 0x00 HARD_HYPHEN 0x07 TAB 0x09 LINE_FEED 0x0a SOFT_HYPHEN 0x0e HARD_SPACE 0x0f Meaning paragraph terminator unbreakable hyphen, not a word delimiter tab character forced line break optional, or potential, hyphen unbreakable space, not a word delimiter Document index record (type 9, variable length){tc "Document index record (type 9, variable length)" \l 3} This record contains a number of six byte entries which are used to apply style and emphasis to the document text. Each entry consists of: • a length (word) • the two character short code of a style • the two character short code of an emphasis The entries conform to the following rules: • the sum of their lengths is one more than the length of the document text record (i.e. the document size, including the final paragraph terminator that is not contained in the document text record). • there is at least one index entry for each paragraph in the document • the final index entry for each paragraph includes the zero that terminates the paragraph • the short codes must correspond with styles and emphases contained in the earlier style data and emphasis data records It must be stressed that a single index entry may not apply to text that is contained in more than one paragraph. Template files{tc "Template files" \l 2} Word processor template files have exactly the same structure as normal word processor files. The only differences are that they: • have a .wrt extension, rather than .wrd; • are stored in a \wdr directory. Template files for program editor aliases of the word processor contain only: • a 40 byte header, as for other word processor files; • a type 1 options data record; • a type 8 document text record. The meanings of some items in the options data record differ from those of a normal word processor file: UWORD cpos the saved cursor position, as for normal word processor files UBYTE symbols the visibility of screen symbols, as for normal word processor files UBYTE backup/statzoom backup state or status window and zoom settings, as for normal word processor files UBYTE style TRUE to set the use of a bold typeface UBYTE mono TRUE to set the use of a monospaced typeface UBYTE outlevel always TRUE for program editor aliases, to enable the use of templates UBYTE spare1 TRUE to specify the use of auto indentation UWORD spare2 the spacing, in column units, for tabs Printer driver font mapping{tc "Printer driver font mapping" \l 2} The font ID associated with a particular emphasis or paragraph style is determined by a selection from the fonts available from the current printer driver at the time the emphasis or style was created. When a different printer driver is installed, the font IDs associated with emphases and styles do not change (so that the exact appearance of the document will be restored when the original printer driver is reinstalled). The actual font to use when printing the document is determined by mapping each fixed font ID to one of the available fonts supplied by the current printer driver. A perfect match occurs when the font ID matches the font number of one of the fonts supported by the printer driver. Otherwise, an attempt is made to make a simple fixed mapping, by font characteristics, onto a basic set of COURIER (mono), HELVETICA (proportional, sans serif) or TIMES_ROMAN (proportional, serif). If the current printer driver does not contain fonts with font numbers HELVETICA or TIMES_ROMAN, thease are also mapped to COURIER (font number zero). This is assumed always to be set for the printer's default font - usually a 10 or 12 point font - whatever it is called. Additional system information {seq chapter readword} Word Processor File Format {page|1} {page|1} {page|1}